home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / CharacterIterator.java < prev    next >
Text File  |  1998-09-22  |  6KB  |  174 lines
  1. /*
  2.  * @(#)CharacterIterator.java    1.7 97/01/20
  3.  *
  4.  * (C) Copyright Taligent, Inc. 1996-1997 - All Rights Reserved
  5.  * (C) Copyright IBM Corp. 1996-1997 - All Rights Reserved
  6.  *
  7.  * Portions copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  8.  *
  9.  *   The original version of this source code and documentation is copyrighted
  10.  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  11.  * materials are provided under terms of a License Agreement between Taligent
  12.  * and Sun. This technology is protected by multiple US and International
  13.  * patents. This notice and attribution to Taligent may not be removed.
  14.  *   Taligent is a registered trademark of Taligent, Inc.
  15.  *
  16.  * Permission to use, copy, modify, and distribute this software
  17.  * and its documentation for NON-COMMERCIAL purposes and without
  18.  * fee is hereby granted provided that this copyright notice
  19.  * appears in all copies. Please refer to the file "copyright.html"
  20.  * for further important copyright and licensing information.
  21.  *
  22.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  23.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  24.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  25.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  26.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  27.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  28.  *
  29.  */
  30.  
  31. package java.text;
  32.  
  33.  
  34. /**
  35.  * This interface defines a protocol for bidirectional iteration over text.
  36.  * The iterator iterates over a bounded sequence of characters.  Characters
  37.  * are indexed with values beginning with the value returned by getBeginIndex and
  38.  * continuing through the value returned by getEndIndex()-1.  The index of the
  39.  * current character can be retrieved by calling getIndex.  Calling setIndex
  40.  * will move the iterator to a new position within the sequence of characters.
  41.  * If at any time the iterator's current index moves outside the range of
  42.  * getBeginIndex and getEndIndex, previous() and next() will return DONE, signaling that
  43.  * the iterator has reached the end of the sequence.
  44.  * <P>Examples:<P>
  45.  *
  46.  * Traverse the text from start to finish
  47.  * <pre>
  48.  * public void traverseForward(CharacterIterator iter) {
  49.  *     for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
  50.  *         processChar(c);
  51.  *     }
  52.  * }
  53.  * </pre>
  54.  *
  55.  * Traverse the text backwards, from end to start
  56.  * <pre>
  57.  * public void traverseBackward(CharacterIterator iter) {
  58.  *     for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
  59.  *         processChar(c);
  60.  *     }
  61.  * }
  62.  * </pre>
  63.  *
  64.  * Traverse both forward and backward from a given position in the text.
  65.  * Calls to notBoundary() in this example represents some
  66.  * additional stopping criteria.
  67.  * <pre>
  68.  * public void traverseOut(CharacterIterator iter, int pos) {
  69.  *     for (char c = iter.setIndex(pos);
  70.  *          c != CharacterIterator.DONE && notBoundary(c);
  71.  *          c = iter.next()) {}
  72.  * int end = iter.getIndex();
  73.  * for (char c = iter.setIndex(pos);
  74.  *     c != CharacterIterator.DONE && notBoundary(c);
  75.  *     c = iter.prev()) {}
  76.  * int start = iter.getIndex();
  77.  * processSection(start,end);
  78.  * }
  79.  * </pre>
  80.  *
  81.  * @see StringCharacterIterator
  82.  */
  83.  
  84. public interface CharacterIterator extends Cloneable
  85. {
  86.  
  87.     /**
  88.      * Constant that is returned when the iterator has reached either the end
  89.      * or the beginning of the text.  The unicode 2.0 standard states that
  90.      * '\\uFFFF' is an invalid unicode value and should not occur in any valid
  91.      * unicode string.
  92.      */
  93.     public static final char DONE = '\uFFFF';
  94.  
  95.     /**
  96.      * Set the position to getBeginIndex() and return the character at that
  97.      * position.
  98.      * @return the first character in the text
  99.      * @see getBeginIndex
  100.      */
  101.     public char first();
  102.  
  103.     /**
  104.      * Set the position to getEndIndex()-1, return the character at that position.
  105.      * @return the last character in the text
  106.      * @see getEndIndex
  107.      */
  108.     public char last();
  109.  
  110.     /**
  111.      * Get the character at the current position (as returned by getIndex()).
  112.      * @return the character at the current position or DONE if the current
  113.      * position is off the end of the text.
  114.      * @see getIndex
  115.      */
  116.     public char current();
  117.  
  118.     /**
  119.      * Increment the iterator's index by one and return the character
  120.      * at the new index.  If the resulting index is greater or equal
  121.      * to getEndIndex(), the current index is reset to getEndIndex() and
  122.      * a value of DONE is returned.
  123.      * @return the character at the new position or DONE if the current
  124.      * position is off the end of the text.
  125.      */
  126.     public char next();
  127.  
  128.     /**
  129.      * Decrement the iterator's index by one and return the character
  130.      * at the new index.  If the resulting index is
  131.      * less than getBeginIndex(), the current index is reset to getBeginIndex()
  132.      * and a value of DONE is returned.
  133.      * @return the character at the new position or DONE if the current
  134.      * position is off the end of the text.
  135.      */
  136.     public char previous();
  137.  
  138.     /**
  139.      * Set the position to the specified position in the text and return that
  140.      * character.
  141.      * @param position the position within the text.  Valid values range from
  142.      * getBeginIndex() to getEndIndex() - 1.  An IllegalArgumentException is thrown
  143.      * if an invalid value is supplied.
  144.      * @return the character at the specified position.
  145.      */
  146.     public char setIndex(int position);
  147.  
  148.     /**
  149.      * Return the start index of the text.
  150.      * @return the index at which the text begins.
  151.      */
  152.     public int getBeginIndex();
  153.  
  154.     /**
  155.      * Return the end index of the text.  This index is the index of the first
  156.      * character following the end of the text.
  157.      * @return the index at which the text end.
  158.      */
  159.     public int getEndIndex();
  160.  
  161.     /**
  162.      * Return the current index.
  163.      * @return the current index.
  164.      */
  165.     public int getIndex();
  166.  
  167.     /**
  168.      * Create a copy of this iterator
  169.      * @return A copy of this
  170.      */
  171.     public Object clone();
  172.  
  173. }
  174.